Day 19 WordPress 對 JavaScript 的編碼標準

第 12 屆 iThome 鐵人賽

DAY 19

自我挑戰組

WordPress 客製化從 0 開始系列第 19 篇

12th鐵人賽 wordpress javascript coding standard

Eric 桓桓

2020-09-20 22:25:31

1180 瀏覽

分享至

大家好，我是 Eric。

今天，就是 JavaScript 篇的最終章。和以往一樣，我們要來說明 WordPress 對 JavaScript 要求的編碼標準。
我們在 HTML 與 CSS 的篇章中提過，編碼標準的目的主要是為了程式風格的一致性。但到了 JavaScript 與 PHP 的篇章中，編碼標準可能同時還會牽涉到程式品質問題，因此在自行開發的過程中，需要更加注意。

JavaScript 編碼標準

我們知道，WordPress 的 JavaScript 有很大一部份都依賴著 jQuery 這款 JavaScript 函式庫，因此在編碼樣式上，WordPress 的開發人員文件提供了 jQuery 開發文件中的編碼樣式，以及另一份〈撰寫一致風格且通順易懂的 JavaScript 之原則〉供開發人員參考。

但開發人員文件中，提出了幾項與 jQuery 編碼樣式不同的編碼標準：

在宣告、定義字串時，使用單引號 (', single quotation)。
在定義 switch/case 的條件時，case 陳述式需要縮排處理。此外，WordPress 原則上不鼓勵使用 switch/case 作為條件式 (從 ES6 開始，有 Map 跟 Set 可以用)。
函式的內容都必須縮排處理，即便整份文件是由一個函式包覆 (譬如定義 $ 的匿名函式)。
為了與 WordPress PHP 的編碼標準保有一致性，因此對空格的使用會與 jQuery 的文件有異。
jQuery 的編碼規則要求每行不得超過 100 字元。對於這項規範，WordPress 建議但不強制。
型別檢測

另外，雖然說有上述的編碼標準，但 WordPress 本身並不建議僅僅為了符合編碼標準，而輕易更動舊的 .js 檔案。比起符合標準，任何重構 JavaScript 的過程，都應該要更重視效能最佳化，以及功能的正確性。

間隔的使用

與 WordPress 的 PHP 編碼標準一樣，在撰寫 JavaScript 時，有幾項關於間隔的要求，這些要求多半是為了要將檔案最小化 (minify) 時，方便程式判斷內容：

使用 tab 進行縮排
行末不應該有空格，這代表無內容的空白行也不應有空格。
每行盡量不要超過 80 字元，建議不要超過 100 字元。
if/else/for/while/try 一定要使用大括號 ({ })，並且要斷行。許多 JavaScript 的教學都會提到：「單行的情況下，可以不需要大括號。」但在正式的專案中，為了程式碼的易讀性，這種作法基本上都是不符合標準的。
一元運算子 (如 ++ 與 --) 與運算元之間不應有空格 (要寫 i++ 而非 i ++)。
, 與 ; 前不能有空格。許多 JavaScript 教學中會提到，即使不加 ;，「有時後」也不會影響瀏覽器判讀，但是這種作法不符合編碼標準，所以不要偷懶。
: 如果作為屬性名稱，則前面不應該有空格。例如 color: "red" 而非 color : "red"。
三元運算 (用 ? 與 : 作為 if/else 的縮寫)，? 與 : 前後都需要有空格。
每個檔案的最後一行，必須是空行。

接下來的三點就是前面所提到，與 jQuery 編碼樣式不同的三項規範：

否定運算元 ! 的後面必須有空格。譬如 if ( ! is_good() )。
函式的內容永遠要有 1 個 tab 的縮排。
每行的開頭只能以 tab 縮排，不應用空格。

多行的處理

如果運算式很長，必須要換行時，用運算子作為行末，而不要作為行首：

// 較差作法
var html = '<p>用 ' + a + ' 和 ' + b + ' 再加上 ' + c
    + ' 會變成 ' + ( a + b + c ) + '</p>';
 
// 較佳作法
var html = '<p>用 ' + a + ' 和 ' + b + ' 再加上 ' + c +
    ' 會變成 ' + ( a + b + c ) + '</p>';

物件

在定義物件時，如果數量少，可以縮為單行，但不應混用。屬性值除非是保留字，否則不應該有引號。

/** 
 * Reference: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/
 */
// 較佳作法
var obj = {
    ready: 9,
    when: 4,
    'you are': 15,
};
var arr = [
    9,
    4,
    15,
];
 
// 在物件與陣列較小的時候，可接受
var obj = { ready: 9, when: 4, 'you are': 15 };
var arr = [ 9, 4, 15 ];
 
// 較差作法
var obj = { ready: 9,
    when: 4, 'you are': 15 };
var arr = [ 9,
    4, 15 ];

陣列與函式的引號間要有間隔

/** 
 * Reference: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/
 */
array = [ a, b ];
 
foo( arg );
 
foo( 'string', object );

// 間隔的最佳作法
var i;
 
if ( condition ) {
    doSomething( 'with a string' );
} else if ( otherCondition ) {
    otherThing( {
        key: value,
        otherKey: otherValue
    } );
} else {
    somethingElse( true );
}
// 檔案的最後必須留空行，並且不要有空格↓

定義變數

在定義變數時，將所有的變數定義於檔案的最上方，也因為集中定義於最上方，因此在作法上，建議一次定義完所有變數，而不要逐行定義：

// 較好作法
var a, b, c, this, that,
    name = 'Eric';
// 較差作法
var a;
var b;
var c;
var this;
var that;
var name = 'Eric';

ES6 開始引進了 const 與 let 兩種定義，const 必須定義在檔案的最上方，而 let 則視情況定義於區塊 (如函式) 的最上方。

全域變數

部分開發人員會使用全域變數的方式來使用 WordPress 核心的變數，此時必須要將使用的全域變數記錄於檔案的最上方。

/* global passwordStrength:true */

上述的註解代表這份檔案中定義了 passwordStrength 這個全域變數。如果是存取其他檔案所定義的全域變數，則把 :true 拿掉，代表這是唯讀的變數。

結尾

說真的，對於初學網站開發的人來說，編碼標準是相當枯燥而且乏味的篇章，因此我也會建議初學者可以跳過這些內容。但如果對於貢獻開源專案有興趣的人，儘管這些內容並沒有辦法讓學習者得到立即的成就感，我還是強烈建議要好好熟悉。編碼標準不僅是統一寫作格式的一套準繩，更是用來理解一個系統架構設計模式不可或缺的重要參考。
寫到這裡，我們已經利用 WordPress 完整的檢視過整個當代網站開發的架構 (HTML5 + CSS + JavaScript) 了。關於這部分的延伸學習，網路上其實有相當多的資源可以參考，我在下方的延伸閱讀中，也列出了我當初學習的參考資源，有興趣的人可以從這些地方入門。
在我們對於當代網站開發有了基本的認識後，我們接下來要進入客製化的另一個核心：PHP。

WordPress 客製化從 0 開始系列 第 19 篇